Skip to content

docs: add Filecoin Pin composition example#49

Draft
lidel wants to merge 1 commit intomainfrom
docs/filecoin-pin-example
Draft

docs: add Filecoin Pin composition example#49
lidel wants to merge 1 commit intomainfrom
docs/filecoin-pin-example

Conversation

@lidel
Copy link
Copy Markdown
Contributor

@lidel lidel commented Apr 12, 2026

Important

do not merge, opening to illustrate how we can keep filecoin-pin details separate, without any maintenance burden.

What

Adds a Archiving to Filecoin README section showing how to chain filecoin-project/filecoin-pin/upload-action after this action so the same CAR is archived to Filecoin. No action.yml changes.

Why composition, not embedding

I prototyped embedding Filecoin Pin as a first-class provider and it does not look feasible in current state of upstream code:

  • Complexity. Other providers have CLI which allow us to havee one-liners in action.yml. Filecoin Pin is ~400 lines of Node.js (Synapse, USDFC top-ups, PDP, IPNI, retry). Not sane. We could revisit if upstream provides better CLI tooling that blackboxes process end-to-end.
  • Permissions. Upstream needs checks: write, pull-requests: write, actions: read for its own check run / PR comment / artifact cache. Every caller would have to grant those, even if they never enable Filecoin. Not feasible, bad opsec.
  • Alpha churn. Upstream's README flags the upload-action as an "educational demo" with breaking changes expected. Embedding ties our release cadence to theirs. Maintenance burden.
  • Duplicate PR comments. Upstream already posts its own (piece CID, data set, provider, retrieval URL). Deduping needs another upstream change.

Composition (this PR) scopes all four to users who actually opt in.

Today vs. after upstream #410

Example works today, but upstream repacks the CAR so the Filecoin CID will differ from ours. Once filecoin-project/filecoin-pin#410 ships, switching to path: build.car makes the CIDs identical.

Revisit when

Filecoin Pin ships a shell-level one-liner comparable to ipfs pin remote add (Pinata) or aws s3 cp --metadata 'import=car' (Filebase). Then embedding becomes cheap and the argument flips.

Show users how to chain filecoin-project/filecoin-pin/upload-action
after this action to archive the same CAR to Filecoin, without
repacking or CID drift. Depends on the upstream change that treats
a `.car` `path` as a pre-built CAR (filecoin-project/filecoin-pin#410).
@lidel lidel added need/community-input Needs input from the wider community status/blocked Unable to be worked further until needs are met labels Apr 12, 2026
@BigLep BigLep added this to FOC Apr 27, 2026
@BigLep BigLep moved this to ⌨️ In Progress in FOC Apr 27, 2026
@BigLep
Copy link
Copy Markdown

BigLep commented Apr 27, 2026

Hi @lidel - thanks for investigating...

Some context: the filecoin-project/filecoin-pin repo has various affordances for using Filecoin Onchain Cloud with an IPFS point of view. The CLI is the main one we use (with underlying JS library) and promote. The filecoin-pin upload-action was intended to be illustrative of how you can use filecoin-pin in an upload action if you want and what a more polished upload action could look like. I see though now that the extra "polish" is actually getting in the way of making it clear that only a simple CLI command is needed.

Obviously please do what you think is right for the ipfs-upload-action. I want to comment on a couple of things:

Other providers have CLI which allow us to have one-liners in action.yml

filecoin-pin has this as well. We can work through additional argument options, but assuming someone has setup a wallet, filecoin-pin add myfile.txt will work after an npm install.

Permissions

Those are the permissions that the example https://github.com/filecoin-project/filecoin-pin/tree/master/upload-action are using. The filecoin-pin CLI doesn't require those. We added those in the sample upload action to show what a more robust or polished github action could look like.

Alpha churn.

Yes, that is valid for the filecoin-pin upload action itself, but not for the filecoin-pin CLI. I see no alpha churn concerns on the filecoin-pin CLI, especially once filecoin-project/filecoin-pin#410 and/or filecoin-project/filecoin-pin#306 ship.

Duplicate PR comments

filecoin-pin CLI will certainly give a lot of output and we'd be happy to reduce its output or allow specification of what output you want if that would make things easier or better for integration into ipfs-deploy-action. (Again, assuming you hook directly into the filecoin-pin CLI, you wouldn't take on all the filecoin-pin upload action comments, etc.)

@rvagg: please feel free to jump in if there's anything you think I've missed or am wrong on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

need/community-input Needs input from the wider community status/blocked Unable to be worked further until needs are met

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[placeholder] Add filecoin-pin support (team/filecoin-pin)

2 participants